Sprite 1984 - 1993/Sprite 1984 - 1993.iso/man/lib.fmt/c/mmap.man

Text File | 1991-04-29 | 13.2 KB | 331 lines

MMAP                  C Library Procedures                   MMAP



NNAAMMEE
     mmap - map an open file into the process's address space

SSYYNNOOPPSSIISS
     NNOOTTEE:: tthhiiss mmaann ppaaggee iiss iinnaaccccuurraattee..  IItt wwaass bboorrrroowweedd ffrroomm aannootthheerr mmaacchhiinnee
     aanndd hhaassnn''tt bbeeeenn uuppddaatteedd ttoo mmaakkee iitt ccoorrrreecctt..
     ##iinncclluuddee <<ssyyss//ttyyppeess..hh>>
     ##iinncclluuddee <<ssyyss//mmmmaann..hh>>

     mmmmaapp((aaddddrr,, lleenn,, pprroott,, sshhaarree,, ffdd,, ppooss))
     ccaaddddrr__tt aaddddrr;;   //** ssttaarrttiinngg vviirrtt--aaddddrr **//
     iinntt     lleenn;;    //** lleennggtthh ((bbyytteess)) ttoo mmaapp **//
     iinntt     pprroott;;   //** RROO,, RRWW eennccooddiinngg **//
     iinntt     sshhaarree;;  //** pprriivvaattee//sshhaarreedd mmooddiiffiiccaattiioonnss **//
     iinntt     ffdd;;     //** ooppeenn ffiillee ttoo bbee mmaappppeedd **//
     ooffff__tt   ppooss;;    //** wwhheerree iinn ffiillee ttoo bbeeggiinn mmaapp **//

DDEESSCCRRIIPPTTIIOONN
     _M_m_a_p causes the file referenced by _f_d, starting at byte _p_o_s
     for _l_e_n bytes in the file, to be mapped into the calling
     process's address space, starting at virtual address _a_d_d_r
     for _l_e_n bytes, using protection specified by _p_r_o_t; modifica-
     tions to the mapped memory are either private to the process
     or shared, as specified by _s_h_a_r_e.  _M_m_a_p can be used to allo-
     cate regions of shared memory, to map files into memory, and
     to access special regions of the physical address space.

     _F_d must reference an open regular (IFREG) or character spe-
     cial (IFCHR) file.  The device driver that implements the
     IFCHR special file must support mapping for this to succeed.
     Typically, a regular file is used to map shared memory.

     The _s_h_a_r_e argument specifies whether modifications to a
     mapped file are to be kept private to the calling process or
     shared with other processes accessing the file.  If _s_h_a_r_e is
     MAP_SHARED, all modifications to the file are shared with
     others who have it concurrently mapped.  If _s_h_a_r_e is
     MAP_PRIVATE, all modifications are local to the calling pro-
     cess; this doesn't restrict other processes from mapping the
     file.  MAP_SHARED and MAP_PRIVATE have no relation to
     _f_l_o_c_k(2), and do not restrict _r_e_a_d and _w_r_i_t_e system-calls.
     If _s_h_a_r_e is MAP_ZEROFILL, the space indicated from _a_d_d_r for
     _l_e_n bytes is replaced by private pages that are zero-filled
     when referenced.  MAP_ZEROFILL ignores the _f_d argument, and
     _p_o_s is ignored other than being checked for alignment
     (specifying fd and pos = 0 is recommended).

     The _p_r_o_t argument should be PROT_WRITE for write access to
     the mapped region, PROT_READ for read access, PROT_EXEC for
     executable access.  These values can be ORed to obtain
     read-write access, etc.  For programming convenience,
     PROT_RDWR is defined as (PROT_READ|PROT_WRITE).  The file



DYNIX                                                           1






MMAP                  C Library Procedures                   MMAP



     access permissions on _f_d must allow the requested access.
     The _p_r_o_t argument affects only the calling process; other
     processes mapping the same file may have different access.

     The _a_d_d_r, _l_e_n, and _p_o_s arguments must be integral multiples
     of the system page size, as defined by _g_e_t_p_a_g_e_s_i_z_e(2).  It
     is possible to map over previously mapped pages.  If _a_d_d_r
     and _l_e_n specify a nonexistent part of the process's address
     space, the process's data segment is grown to accommodate
     the request, and the process ``break'' (see _b_r_k(2)) is set
     to the high end of the mapped region.  Reference to any
     ``holes'' between the mapped region and the rest of the data
     segment result in a segmentation fault (SIGSEGV).  _m_m_a_p does
     not allow mapping over text or stack pages.

     When memory is mapped to a regular file, the file acts like
     a paging area for the mapped memory region.  _R_e_a_d and _w_r_i_t_e
     operations to mapped regions of the file also affect the
     corresponding memory.  The memory contents are copied out to
     the file when the process is swapped or when it exits, or
     when the region is otherwise unmapped by the last process
     that has it mapped.  For programs that use shared memory but
     do not need a permanent disk image of the memory, the file
     associated with _f_d can be _u_n_l_i_n_ked (see _u_n_l_i_n_k(2)) even
     before the call to _m_m_a_p: if the file is _u_n_l_i_n_ked when the
     region is unmapped, the disk space will not be updated.

     Regular files have their size rounded up to a file-system
     block boundary.  Any non-existent space in the file at the
     time of the _m_m_a_p request (for example, in a sparse file) is
     allocated, and filled with zeroes when referenced.  Both of
     these operations require write access to the file.

     The type of file referenced may impose further restrictions
     on the _p_o_s, _o_f_f_s_e_t, or other parameters.  Refer to the
     manual entry of the relevant device driver (for example,
     _p_m_a_p(4)) for details.

     Closing a file descriptor previously used in an _m_m_a_p opera-
     tion unmaps all pages mapped by that file descriptor (see
     also _m_u_n_m_a_p(2)).  (Note: this may change in order to provide
     compatibility with sunOS.) If the file-descriptor has been
     _d_u_ped prior to being closed, no unmap takes place.

     _M_m_a_p can be called multiple times with the same file
     descriptor, resulting in several (possibly overlapping)
     mapped regions.  A process can have up to 8 regions mapped
     simultaneously; mappings that are completely overlapped by
     subsequent mappings are not counted in this total.  Mappings
     which use the same file descriptor, and addr and pos argu-
     ments which align virtually with a previous mapping, also
     don't count in this total; the simplest case is mapping more



DYNIX                                                           2






MMAP                  C Library Procedures                   MMAP



     of a file, starting from the end of a previous mapping.

     All mapped files remain mapped in both the parent and child
     process after a _f_o_r_k.  All flavors of the _e_x_e_c and _e_x_i_t sys-
     tem calls, when successful, remove all maps the calling pro-
     cess had established.  If a process has any maps, _v_f_o_r_k
     behaves exactly like _f_o_r_k.  A child of a _v_f_o_r_k that has not
     yet _e_x_e_ced a new image cannot successfully execute _m_m_a_p.

     There are three types of mapping: paged, physical, and non-
     paged memory.  The type of mapping is determined by the type
     of file being mapped.  Paged maps support shared memories
     and mapped regular files.  Physical maps deal with hardware
     that has restrictive access capability (for example, the
     MULTIBUS address space, including Atomic Lock Memory).
     Non-paged memory maps are typically used for special
     reserved areas of system memory; they are assumed to behave
     exactly like memory, supporting accesses of arbitrary size
     and alignment, DMA, etc.

     System services (raw IO, read/write, stat, etc.) are sup-
     ported in paged and non-paged memory maps; attempts at such
     services in physically mapped address space result in an
     error, typically EFAULT.  Core dumps include a copy of any
     mapped address space; however, physically mapped addresses
     read as zero.

     Regular files (IFREG) are always page-mapped.  Character
     special files (IFCHR) can support paged, physical, or non-
     paged maps, depending on the underlying hardware.  Physical
     and non-paged maps are always valid in the process address
     space; references won't cause a page fault.

     When _m_m_a_p increases a program's address space, it also
     attempts to increase its allowable resident set size.

RREETTUURRNN VVAALLUUEE
     _M_m_a_p returns the address of the mapped region when success-
     ful.  (Note: this may change, as some Unix machines return
     0.) Otherwise it returns -1 and places the error number in
     the global variable _e_r_r_n_o.

EEXXAAMMPPLLEESS
     The following code sets up a 1-Mbyte region of shared memory
     at the first page boundary above the current program
     ``break.'' This region will be shared with the process's
     children and with any other process that maps the file
     ``shmem''.  pgsz = getpagesize(); shm_base = (char *) (
     ((int)sbrk(0) + (pgsz-1)) & ~(pgsz-1) ); fd = open ("shmem",
     O_CREAT | O_RDWR, 0666); mmap (shm_base, 0x100000,
     PROT_RDWR, MAP_SHARED, fd, 0);




DYNIX                                                           3






MMAP                  C Library Procedures                   MMAP



     The following code maps the first page of Atomic Lock Memory
     into the process's virtual address space at address
     0x200000.  This region will be shared with the process's
     children and with any other process that maps the file
     ``/dev/alm/alm00''.  pgsz = getpagesize(); fd = open
     ("/dev/alm/alm00", O_RDWR, 0); mmap (0x200000, pgsz,
     PROT_RDWR, MAP_SHARED, fd, 0);

EERRRROORRSS
     [EINVAL]       _A_d_d_r, _p_o_s, or _l_e_n is not a multiple of the
                    system page size.

     [EINVAL]       _P_r_o_t did not specify at least one of
                    PROT_WRITE or PROT_READ; _s_h_a_r_e did not
                    specify MAP_SHARED, MAP_PRIVATE, or
                    MAP_ZEROFILL; or _s_h_a_r_e specified MAP_ZEROFILL
                    but _p_r_o_t did not contain PROT_RDWR.

     [EINVAL]       _F_d does not represent a regular or character
                    special file.

     [EINVAL]       The process is the child of a _v_f_o_r_k.

     [EINVAL]       The area defined by the _a_d_d_r and _l_e_n argu-
                    ments overlaps text or stack pages of the
                    process.

     [ENODEV]       The device driver indicated by _f_d does not
                    support mapping.

     [ENOMEM]       There is no swap space for the page table of
                    a mapped regular file, or you are trying to
                    create too large a process.

     [EMFILE]       The system-defined per-process limit on the
                    number of _m_m_a_ped files (currently 8) was
                    exceeded.

     [ENFILE]       The system-wide limit on the number of mapped
                    regular files was exceeded.  This limit is
                    defined by the variable _n_m_f_i_l_e in
                    /_s_y_s/_c_o_n_f/_p_a_r_a_m._c.

     [EACCES]       _F_d does not allow the desired access (read or
                    write), or a write-only file descriptor was
                    used.

     [EACCES]       A mapped regular file must be extended to a
                    file-system block boundary, or the file must
                    have space allocated, and the file descriptor
                    is read-only.




DYNIX                                                           4






MMAP                  C Library Procedures                   MMAP



     [ENOSPC]       A mapped regular file was sparse and there
                    was insufficient space in the file-system to
                    satisfy the request.

     [EFBIG]        The _p_o_s and _l_e_n arguments would create too
                    large a file.

     [others]       Other error values may be returned by some
                    device drivers when requested to map.  See
                    the relevant driver manual entry for details.

SSEEEE AALLSSOO
     munmap(2), pmap(4), vm_ctl(2), fork(2), exec(2), get-
     pagesize(2), msync(2), mlock(2), munlock(2), mincore(2)
     _G_u_i_d_e _t_o _P_a_r_a_l_l_e_l _P_r_o_g_r_a_m_m_i_n_g

BBUUGGSS
     A mapped file may not be truncated.

     If a file is extended to a file-system block boundary, its
     original size is lost.

     Current restrictions on what parts of the address space can
     be re-mapped should be lifted.

NNOOTTEESS
     Due to a hardware restriction, PROT_WRITE implies PROT_READ
     also.  PROT_EXEC is ignored.

     To minimize overhead, mapped regions should be kept as close
     as possible to the low end of process memory.

     Address space holes under the process ``break'' read as
     zeroes in core files.





















DYNIX                                                           5